doc: drop usage of numfig/numref #56631
Conversation
Usage of numfig=True option in conf.py significantly increases doc build time. While it is a nice feature, it's not extensively used in Zephyr documentation, so let's remove its usage in favor of faster doc builds. Signed-off-by: Gerard Marull-Paretas <[email protected]>
|
https://github.com/zephyrproject-rtos/zephyr/actions/runs/4631147648/jobs/8193645328?pr=56631 still takes 11.5 min which is disappointing; no major speed up. Compared to #55708 it is still running Or maybe |
With the numbers we have, there's not enough evidence that removing numfig has a positive performance impact. I'll close this for now. |
|
What (new?) numbers do you have? The only number I've seen for incremental build (the only build that matters in this case) is the one I posted in #55708 and the difference was huge. |
|
tl;dr: please test the incremental build and re-open this. I re-tested with the latest version of everything:
Same system as in #55708. Removing Disabling |
This reverts commit 4516117. A git bisect showed that the duration of an incremental build doubled after this commit enabled `numfig=True`. Measurements shared and discussed in zephyrproject-rtos#37572, zephyrproject-rtos#55708 and zephyrproject-rtos#56631 confirmed this. Here are yet more measurements below in two different system configurations building docs for very recent Zephyr commit b10817b + all `:numref:` removed by the previous commit. In other words these numbers show the cost of `numfig=True` _without_ even using `:numref:`. * Ubuntu 22, 8 cores sphinx-build --version 4.3.2 numfig=True numfig=False - from scratch 7 min 15 s 6 min 40 s - one-line .rst change 48 s 24s * Current Arch Linux, 72 cores sphinx-build --version 6.2.1 numfig=True numfig=False - from scratch 5 min 0 s 4 min 50 s - one-line .rst change 37 s 18 s Signed-off-by: Marc Herbert <[email protected]>
This reverts commit 4516117. A git bisect showed that the duration of an incremental build doubled after this commit enabled `numfig=True`. Measurements shared and discussed in #37572, #55708 and #56631 confirmed this. Here are yet more measurements below in two different system configurations building docs for very recent Zephyr commit b10817b + all `:numref:` removed by the previous commit. In other words these numbers show the cost of `numfig=True` _without_ even using `:numref:`. * Ubuntu 22, 8 cores sphinx-build --version 4.3.2 numfig=True numfig=False - from scratch 7 min 15 s 6 min 40 s - one-line .rst change 48 s 24s * Current Arch Linux, 72 cores sphinx-build --version 6.2.1 numfig=True numfig=False - from scratch 5 min 0 s 4 min 50 s - one-line .rst change 37 s 18 s Signed-off-by: Marc Herbert <[email protected]>
This reverts commit 4516117. A git bisect showed that the duration of an incremental build doubled after this commit enabled `numfig=True`. Measurements shared and discussed in zephyrproject-rtos#37572, zephyrproject-rtos#55708 and zephyrproject-rtos#56631 confirmed this. Here are yet more measurements below in two different system configurations building docs for very recent Zephyr commit b10817b + all `:numref:` removed by the previous commit. In other words these numbers show the cost of `numfig=True` _without_ even using `:numref:`. * Ubuntu 22, 8 cores sphinx-build --version 4.3.2 numfig=True numfig=False - from scratch 7 min 15 s 6 min 40 s - one-line .rst change 48 s 24s * Current Arch Linux, 72 cores sphinx-build --version 6.2.1 numfig=True numfig=False - from scratch 5 min 0 s 4 min 50 s - one-line .rst change 37 s 18 s Signed-off-by: Marc Herbert <[email protected]>
2 participants
Usage of numfig=True option in conf.py significantly increases doc build time. While it is a nice feature, it's not extensively used in Zephyr documentation, so let's remove its usage in favor of faster doc builds.
TODO: compare build times (cold/incremental)